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SUMMARY 



Trident CCSMA requested the Naval Postgraduate School to evaluate 
the "Maintainability Enhancement for TCP/TSP Revision 6.0 Update .20," 
referred to as 6.0/. 20. The approach for accomplishing this task was to 
compare 6.0/. 20 for compliance or conformity with applicable sections of 
SECNAVINST 3560.1, FIPS PUB 38, AND MIL- STD 1679. In addition, a 
sample of 6.0/. 20, Volume 2, was examined in some detail for its useful- 
ness as a software maintenance tool in terms of consistency, completeness, 
understandability , and absence of errors. Many suggestions for improve- 
ment have been made . 

Our conclusions are that 6.0/. 20: 

Does enhance maintainability. However, we believe listings 
alone, even if they are structured, are inadequate for mainten- 
ance purposes. 

Does not include coverage of significant applicable items called 
for in 3560.1, FIPS PUB 38, and 1679. 

Appears to be incomplete and to contain a moderate amount of 
inconsistencies, ambiguities, and errors. 

Could provide an excellent software maintenance tool if its 
quality were improved in accordance with the suggestions made 
in this report. 
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I. 



INTRODUCTION 



A. Purpose 

Trident CCSMA has requested the Naval Postgraduate School (NPS) to 
evaluate the "Maintainability Enhancement for TCP/TSP Revision 6.0 
Update .20" documents, subsequently referred to as 6.0/. 20, with 
respect to its usability for maintaining Trident Command and Control 
System software. 

3. Approach 

It is understood that one of the governing documents for the pro- 
duction and use of Trident software is "Department of the Navy Tactical 
Digital Systems Documentation Standards," SECNAVINST 3560.1, 3 August 
1974. Therefore, it was deemed appropriate to use this standard as 
one means of evaluating the subject documents. It was felt that, as a 
minimum, documentation used on the Trident project should meet the 
applicable sections of this standard. However, recognizing that this 
standard was issued many years ago and that the field of software 
engineering has evolved in the interim, additional criteria which 
reflect more modern software design and maintenance techniques were 
used in the evaluation. 

The part of 3560.1 which appears to be most applicable to maintenance 
is the Program Description Document, pages 2-137 to 2-152. As stated 
in this document, its purpose, in part, is the following: "As a detailed 
compendium of the subprogram structure, the Program Description document 
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will serve as the essential instrument for subsequent use by operational, 



maintenance , and contractor personnel diagnosing troubles, making 
adaption changes , designing and implementing modifications to the 
system, and introducing or adding new subprogram functions to the 
completed program" (underlining added by the author) . 

Another means of evaluation was with respect to the publication 
"Guidelines for Documentation of Computer Programs and Automated Data 
Systems," National Bureau of Standards, Federal Information Processing 
Standards Publication 38 (FIPS PUB 38), February 15, 1976. As stated 
in FIPS PUB 38, its purpose is the following: "These guidelines pro- 

vide a basis for determining the content and extent of documentation for 
computer programs and automated data systems. Software development 
phases and related document types are identified, several examples of 
documentation options are given, and content guidelines for ten document 
types are provided." Although, officially, this guideline is not 
applicable to Trident software because it was written to apply to ADP 
systems under the provisions of Public Law 89-306 (Brooks Bill) , which 
excluded embedded computer systems , it is of technical interest because 
it is one of the few Federal Government software guidelines which 
covers program maintenance. 

As stated in FIPS PUB 38, "The purpose of the Program Maintenance 
Manual is to provide the maintenance programmer with the information 
necessary to understand the programs, their operating environment, 
and their maintenance procedures." The Program Maintenance Manual 
is described on pages 45-47 of FIPS PUB 38. 

It was also considered important to examine 6.0/. 20 with respect 
to the applicable sections of MIL-STD 1679 (Navy), 1 December 1978, 
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the Navy's Military Standard for Weapon System Software Development. The 
applicable section of 1679 is primarily 5.11 Configuration Management, 
pages 23-24. 

C. Scope 

In order to ensure good software maintainability, it is necessary 
to use sound programming methodology and procedures, as well as pro- 
vide good documentation. It is difficult to evaluate the quality of 
documentation and not also consider the quality of the product that 
has been documented, because good documentation of non-structured pro- 
grams which contain machine language code, although of some benefit, 
will not result in good software maintainability, nor will good docu- 
mentation of highly patched programs allow software to be easily 
maintained. In other words, if programs are inherently difficult to 
change and understand and may not have been designed with maintain- 
ability in mind, documentation may only make a marginal contribution 
to the improvement of maintainability. Thus, this project poses a 
dilemma because we have been asked to review and evaluate documentation 
for programs which are non-structured, contain significant amounts of 
machine language code, and are highly patched. It is understandable 
that this is the case, since the programs were designed prior to the 
availability of a mature structured programming methodology and high 
level languages for tactical system software development. In addition, 
although machine language patching is generally considered to be un- 
desirable, for certain administrative and contractual reasons it is a 
prevalent practice in Navy embedded computer software development. The 
argument can be made. that, because of these practices + good documentation is 
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even more important in this environment than it would be in those 
situations where the use of structured programming and high level 
languages provide a degree of self -documentation . Accordingly, the 
scope of this paper will be limited to evaluating the adequacy of 
6.0/. 20 for maintaining the TCP/TSP software, ignoring what is per- 
haps the more fundamental maintenance issue of the adequacy of the 
underlying software. 

A major assumption of this study which affects its scope is that 
the 6.0/. 20 documentation is to be evaluated independently of the 
program listings. It is noted that listings are not included in the 
version of 6.0/. 20 dated 29 September 1979, although these were included 
in a prior version (undated) . Quoting from Volume 1 of the version 
dated 29 September 1979, "The primary goal is to improve this software’s 
maintainability by making the programs and their patches understandable 
and visible in a single simplified form," (underlining added by the 
author) . The implication which has been derived based on the above 
statement and the fact that the listings are not included in the 
latest version, is that 6.0/. 20 is to be used for maintenance pur- 
poses primarily on a stand-alone basis with listings utilized as a 
secondary source of information. This interpretation is critical 
with respect to some of the results obtained in this study , because 
certain deficiencies in 6.0/. 20, which are noted later in this report, 
regarding such items as data design, tables and indexes, are not 
addressed by 6.0/. 20 but are covered in the listings. If it was the 
intent to use the listings with 6.0/. 20 in a coordinated fashion, it 
would be helpful to provide a detailed cross-referencing between the 
two. A method for accomplishing this cross-referencing is suggested 
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in a later section. The scope of this report is limited to considering 
6.0/. 20 as an independent tool for maintenance which does not rely exten- 
sively on the use of program listings. However, since the flowcharts 
are based on the program logic, as expressed in the listings, it was 
necessary to make extensive reference to the listings in this report 
in order to understand and evaluate 6.0/. 20. In fact, a result of this 
analysis was the conclusion that the two mediums should be used as an 
integrated documentation package and not in isolation. 
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II. EVALUATION OF 6.0/. 20 



A. With Respect to SECNAVINST 3560.1, Program Description Document, 
Pages 2-137 to 2-152. 

The following 3560.1 pages and sections are covered by 6.0/. 20: 



Page 


Section 


Title 


2-141 


1 . 


Scope 



2-141 


2. 


Applicable Documents 


2-142 


3. 


Requirements 


2-142 


3.1 


Subprogram Detailed- Description 


2-143 


3.2 


Subprogram Flow Diagrams 


2-148 


3.6 


Conditions for Initiation 


2-149 


3.8 


Interface Description 



The 3560.1 pages and sections which apparently are not covered by 



6.0/. 20 are identified below. It is possible that these sections are 
not applicable to certain volumes of 6.0/. 20. However, the named missing 
sections were not found in any of the 6.0/. 20 volumes for which copies 
were provided to NPS, so it is assumed that it was not intended to 
include these sections in 6.0/. 20. A brief description of the intended 



contents of the missing 
Page Section 

2-144 3.3 

2-144 3.3.1 



sections as specified by 
Title 

Subprogram Data Design 
Tables 



3560.1 is given: 

Contents 

General summary descrip- 
tion of the subprogram 
data base. 

Detailed description of 
each table used in the 
subprogram data base: 

a . Table name . 

b. Purpose and type. 

c. Size and indexing 
procedure. 

d. Structure and bit 
layout . 



10 



2-145 



3.3.2 



Variables 



2-145 



2-145 



2-146 



2-146 



2-148 



2-149 



3.3.3 Flags 



3.3.4 Indexes 



3.3.5 Common Data Base 
Reference 



Detailed description of 
each variable used in 
the subprogram data 
base : 

a. Variable name. 

b. Purpose. 

c. Structure and bit 
layout . 

Detailed description of 
each flag used in the 
subprogram data base: 

a. Flag name. 

b. Purpose and status. 

c. Structure and bit 
layout . 

Technical description 
of each index used in 
the subprogram data 
base : 

a. Index name. 

b. Purpose. 

Complete list of all 
references to local 
and common data base 
items and the location 
of each reference. 



3.4 Input/Output Formats Brief description and 

graphic (sample) repre- 
sentation of each input 
and output message , 
card format, tape for- 
mat, etc. processed by 
the subprogram. 

3.7 Subprogram Limitations Summary of any known or 

anticipated limitations 
of the subprogram. 

4. Quality Assurance Reference to all appli- 

Provisions cable test plans and 

procedures that have 
been used for verifica- 
tion of the subprogram. 
(6.0/. 20 should reference 
the Trident Test Speci- 
fication Requirements 
and Test Procedures 
which are described in 
Refs. 1 and 2 . ) 
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NOTE: It was not possible to determine whether Section 3.5 Required Sys- 

tem Library Subroutines was covered by 6.0/. 20 because it was not known 
whether library subroutines were used. 

B. With Respect to FIPS PUB 38 , Program Maintenance Manual , Pages 45-47 

The following Program Maintenance Manual sections are covered by 6.0/. 20 
Section Title 



1 . 


General Information 


1.1 


Summary 


1.2 


Environment 


1.3 


References 


2. 


Program Descriptions 


2.1 


Program Identification 


2.1.1 


Problem and Solution Method 


2.1.2 


Input (description of) 


2.1.3 


Processing (logic , linkages 
handling) 


2.1.4 


Output (description of) 


2.1.5 


Interfaces 


2.1.7 


Run Description 


3. 


Operating Environment 


3.2 


Support Software 


3.2.1 


Operating System 


3.2.2 


Compiler, Assembler 



The Program Maintenance Manual sections which apparently are not 
covered by 6.0/. 20 are identified below. The caveats that were stated 
relative to 3560.1 also apply to this section. 
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Section 



Title Contents 



2.1.2 


Input 


Layout, medium, codes, units of 
measurement, format, range of values 
or reference to a data element 
dictionary. 


2.1.3 


Processing 


Variables , constants , restrictions , 
switches, flags. 


2.1.4 


Output 


Layout, medium. 


2.1.6 


Tables 


Identification, content, location, 
structure , purpose . 


3.1 


Hardware 


Equipment required for operation of 
system and for each program. 


3.3 


Data Base 


Description of data bases used or 
reference to a data element dictionary 
(codes, units of measurement, format, 
range of values) . 


4. 


Maintenance 


Procedures 



4.1 Programming 

Conventions 



Identification and descriptions. 



4.2 



4.3 



4.4 



4.5 



Verification Description of procedures to check 

Procedures the performance of programs , in 

general and following modification. 
Reference to test data and testing 
procedures. (6.0/. 20 should 
reference the Trident Test Specifi- 
cation Requirements and Test Pro- 
cedures which are described in 
Refs. 1 and 2) . 



Error Correction Description of error conditions. 
Procedures sources and procedures for correc- 
tion. (6.0/. 20 should reference 

the Trident CCS Problem Reporting 
and Modification Systems which are 
described in Refs. 1 and 2.) 



Special 

Maintenance 

Procedures 



Description of special procedures 
which change with time or conditions 
(e.g., change of parameters, algo- 
rithms) . 



Listings and Information about how to obtain 

Flowcharts copies of listings and flowcharts. 
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NOTE: It is possible that Section 3.3 Data Base is not applicable to 

any of the programs documented by 6.0/. 20. 

C. With Respect to MIL-STD 1679 (Navy) , Configuration Management , 

Pages 23-24 

The following configuration management sections of 1679 are covered 
by 6.0/. 20: 

Section Title 

5 . 11 Configuration Management 

5.11a Positive identification of all program components 

5.11.1 Configuration Identification 

5.11.1.1 Baselines 

5.11.1.2 Documentation Identification 

5.11.1.2a Component 



The sections which apparently are not covered by 6.0/. 20 are 
identified below. The caveats that were stated relative to 3560.1 
also apply to this section. 



b. Purpose 



c. Baseline 



d. Serial, edition and change status 



Section 



Title 



5.11b 



Treatment of proposed changes to components under 
configuration control. 



5.11c 



Implementation of approved changes and dissemination 
of corrected documentation and program changes. 



5. lid 



Recording of status of all proposed changes. 



5. lie 



Verification of change control, identification and 
status account of documentation and program materials. 
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5.11.2 Configuration Control 


Procedures for formal 
control of all docu- 
ments , program materials 
and support library 
shall be established. 


5.11.2.1 Software Changes 


Proposed changes to 
software which is 
under configuration 
control shall be 
submitted to the ap- 
propriate software 
configuration control 
boards . 


5.11.2.2 Documentation Changes 


Procedures for control- 
ling preparation and 
dissemination of changes 
to documentation shall 
be developed. 


5.11.2.3 Software Configuration 

Control Boards 


Each baseline plus 
approved changes from 
those baselines shall 
be under the formal 
control of a respon- 
sible board. 


5.11.3 Configuration Status 

Accounting 


Procedures to enable 
the generation of 
periodic status reports 
on all components under 
configuration management 
shall be established. 



With respect to the above sections, 6.0/. 20 should reference the 
Trident CCS Problem Reporting and Modification Systems and the Configu- 
ration Management System which are described in Refs. 1 and 2. 
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III. OTHER COMMENTS 



The following coinments pertain to 6.0/. 20 Volume 2, using it as 
an example. 

A. Functional Description, on Pages 3-1 to 3-3 

1. The discussion would be more meaningful if it were keyed to the 
hierarchical structure diagrams and to the flowcharts. For example, 
definitions and descriptions of pertinent interrupts should be provided, 
including important symbolic addresses which are utilized. This informa- 
tion and the interrupt numbers should be related to the diagrams. 

2. Sub-headings for the various sections, such as "Interrupt 
Handling," would make the text more readable. 

3. Some typos were observed which affect understandability . For 
example, the fifth line in the second paragraph on page 3-3. 

4. Although this comment does not concern quality of documentation, 
it was noted on page 3-2 that the control memory test for all zeros and 
all ones should be preceded by setting the relevant portions of main 
memory to non-zero and non-one data, respectively, prior to the transfer 
of control memory to main memory. 

B. Hierarchical Structure Diagrams 

1. Hierarchical structure diagrams and flowchart symbols should 
be defined at the beginning of each volume. It is not clear that these 
diagrams strictly adhere to ANSI standards (see Reference 3) . 
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2 . A consistent hierarchical structure box numbering system should 

be utilized which would indicate at a glance two important pieces of 
information: the function (e.g., "Periodic Entry") to which the routine 

belongs, and the level of the routine within the function. This scheme 
is shown on the accompanying hierarchical structure diagrams, which were 
reproduced from Volume 2 (pages 4-4 to 4-8) . The left digit is function 
number, the middle digit is level number and the right digit is routine 
number for a given level and function. Level numbers start at "1" 

and increase from top to bottom; routine numbers start at "1" and 
increase from left to right. These numbers should be referenced to 
the pertinent flowcharts, as shown on the accompanying diagrams (pages 
4-9 to 4-12 of Volume 2) . As a means of tying together hierarchical 
structure diagrams, flowcharts and listings, the identification numbers 
could be appended to the listings as shown on the reproduced CMS- 2 
Assembler listing (page 6 of listing) , which is attached. Two columns 
are utilized: one is the "At" column corresponding to lines with labels; 

the other is the "To" column corresponding to lines with transfer of 
control. Perhaps these identifiers could be punched and printed in 
formatted columns as part of the "Comments" field. A further help would 
be to sort source statements by the "At" column and to indent based on 
the middle digit. This would provided a structured listing of an entire 
function in contiguous locations. 

3. Although it is not a fault of the flowcharting process, it 
was observed that there is a similarity of labels (e.g., CTPRE and 
CTPER) . This could lead to error in software maintenance. 



17 



C. Flowcharts 



1. The entry to a flowchart page should be annotated with the flow- 
chart page numbers which are associated with the source (s) of the trans- 
fer of control and the exit(s) from a flowchart page should indicate 

the page number (s) which are associated with the destination (s) of the 
transfer of control. This is shown on the attached pages 4-9 to 4-12 
of Volume 2. 

2. There is no loop back to CTPERl on page 4-9 of the flowcharts, 

as indicated by the JBNZ instruction at line 223 on page 6 of the 
listing. Instead the box at the bottom of page 4-9 reads: "Repeat Data 

Pattern Test Using ' IWC* Control Word." Similarly there is no loop 
back to CTPER2 on page 4-10 nor loop back to CTPER3 on page 4-11, as 
shown by line 230 and 238, respectively, on the listing. This method 

of presentation seems to mask an important characteristic of the 
program logic. 

3. There seem to be discrepancies between flowcharts and listings. 
For example, the second box from the bottom of page 4-11 figure 4.3 
refers to IWC. Page 6, lines 243 and 244 refer to ICW. The box in 
the flowchart also refers to "Set Up Class IV," while line 243 on the 
listing refers to Class II. 

D. Interpretation of Hierarchical Structure Diagrams 

1. Using Volume 2 as an example, it appears that the hierarchical 
structure diagrams are not totally accurate in portraying program logic. 
For example, the following discrepancies were noted between hierarchical 
structure and the listings: 
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a. With respect to page 4-5, figure 4.2, CTPER is shown 
superior to all other routines on this chart, yet an analysis of the 
listing reveals that CTPER only happens to be the first label in this 
series of code and its only paths to other labels are to CTPERl and 
CTP ERROR. The latter reference brings to light another discrepancy. 
CTPER does have a conditional branch to CTP ERROR in the listing (line 
219), but according to figure 4.2, there is no path between these 
routines. Wtih respect to figure 4.2, the listings indicate the follow 
ing access paths among routines: 

- CTPER accesses CTPERl and CTPERROR. 

CTPERl accesses CTPER2 and CTPERROR. 

- CTPER2 accesses CTPER3 and CTPERROR. 

CTPER3 accesses CTRTN and CTPERROR. 

Thus, a more accurate picture of this logic is shown in the diagram 
labeled "Revised Figure 4.2 CT Hierarchical Structure (2 of 5)." It 
should be noted that in this diagram the horizontal lines indicate 
paths between adjacent code segments that are in the same module and 
vertical lines indicate paths involving transfer of control. Also, 
the arrows, from left to right and from top to bottom, indicate the 
general direction of control flow. In large measure the "routines'* 
which have been shown as hierarchical structures boxes in Volume 2 
are simply labels in a segment of code. This has been pointed out in 
Volume 2 on page 4-3. The difficulty in constructing the hierarchical 
structure from program listings is that by definition, the diagrams 
are supposed to indicate hierarchy, i.e., superior-subordinate relation 
ships, and programs designed using a top-down approach. Since the 
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programs were not written this wav, the imposition of a hierarchical 
structure on a coding format that is inherently non-structured will 
lead to incompatibilities between diagrams and listings , unless great 
care is exercised in performing the translation. 

b. Pages 4-7 and 4-8, figure 4.2, show CTKLAS2 as having access to 
CTKLASY. The listing indicates that this actually occurs via CTKLIPI 
(lines 314 and 342), which is not listed as a routine in figure 4.1, 
page 4-2 of volume 2. CTKLIPI also has a path to CTARITH via CTKL2XIT 
at line 349. Page 4-8 also shows no path between CTKAS2I and CTKLASY*. 
However, the listing shows this path to exist. This condition was 
verified by consulting the CMS-2 Assembler List Cross Reference Table. 
One of these references to CTKLASY occurs from the same routine. 

Pages 4-7 and 4-8 show no path between CTKLAS2 and CTKLAS2Z. 
However, line 335 on the listing shows that this label is contained 
within routine CTKLAS2 . 

Page 4-8 shows no path between CTKLASY and CTKLAS2J. A 
check of the List Cross Reference Table revealed that this path does 
exist; this reference to CTKLAS2 J occurs at line 430. However, this 
path is used only when a 4 stop condition does not exist. 

Taking the above difference into account, page 4-8 has been 
redrawn and is labeled as "Revised Figure 4 . 2 CT Hierarchical Structure 
(5 of 5)." Again, the procedure was to use horizontal arrows (going 
into side of box) to indicate adjacent code segment relationships 
(e.g., between CTKLAS2 and CTKLAS2Z and between CTKLAS2I and CTKLAS2 J) 
and vertical arrows (going into top of box) to show transfer of control. 



*At least it is not unambiguous as to whether there is a path between 
CTKLAS2 and CTKLASY or between CTKLAS2I adn CTKLASY, or both. 
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Note: The revised hierarchical structure diagrams would 

obviously have different numbers for some boxes than those used in 
Section B.2. The latter was based on the given hierarchical structure 
diagrams as shown in Volume 2 . 

c. It was not clear in what sense lines with arrows and those 
without arrows were used in the hierarchical structure diagrams of 
Volume 2. If the use of arrows was to show transfer of control and the 
absence of arrows to tie together routines of the same module, the 
method would be inconsistent because there are no arrows on the lines 
which connect CTKLAS2 to CTKLAS2 (A-I) in figure 4.2 of Volume 2. 

E. Inter-Module Message Tables 

These tables, such as the one on page 4-34, figure 4.4, Volume 2, 
should indicate the page number of the flowchart of the referenced 
procedure (routine) . 

F . Configurations 

The hardware and configuration to which 6.0/. 20 applies should be 
defined in each volume. 

G. Patch Listings 

Patch listings in Volume 1 should have column headings. 

H. Audit Comments 

Although we do not agree with the comment on page A-l, Volume 2 
that, "... the module is readily understandable even though it is 
non-modular , " we do feel that this is a valuable part of maintenance 
documentation. Perhaps this section could be expanded. 
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Page 4-5 
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FIGURE 4.2 CT Hierarchical Structure 
Page 4-6 
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FIGURE 4.2 CT Hierarchical Structure (4 of 5) 
Page 4-7 
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REVISED FIGURE ‘1.2 CT HIERARCHICAL STRUCTURE (2 OF 5) 

REVISED Page 4-5 
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(1) Used only when a 4 stop condition does not exist, 

REVISED FIGURE 4.2 CT HIERARCHICAL STRUCTURE (5 OF 5) 
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